npm link与发布内容控制

本地调试、发布内容过滤、打包验证是包发布前三个关键环节。

npm link本地调试

基本用法

在包项目目录创建全局链接：

cd my-lib
npm link

在使用方项目引用：

cd my-app
npm link my-lib

此时my-app中的require('my-lib')指向my-lib源码目录，修改实时生效。

取消链接

# 在使用方项目
cd my-app
npm unlink my-lib

# 在包项目
cd my-lib
npm unlink -g

常见问题

• link后依赖缺失：在my-lib目录执行npm install
• peer依赖警告：link不检查peer依赖版本
• 多包联调：每个包分别执行npm link

npm link创建的是符号链接，与真实安装行为有差异。发布前务必用npm pack模拟真实安装测试。

files字段控制发布内容

files白名单

{
  "name": "my-lib",
  "files": [
    "dist",
    "lib",
    "README.md",
    "LICENSE"
  ]
}

files指定哪些文件/目录包含在发布包中，未列出的文件不会被打包。

默认包含与排除

始终包含：

• package.json
• README.md
• LICENSE / LICENCE
• main字段指向的文件

始终排除：

• .git
• node_modules
• .npmrc
• package-lock.json

.npmignore排除

src/
test/
.eslintrc.json
tsconfig.json

.npmignore语法与.gitignore相同，从files白名单中再排除。

files白名单优先于.npmignore。推荐优先使用files字段，更直观且不易遗漏。

npm pack打包测试

基本用法

npm pack

生成my-lib-1.0.0.tgz，内容与npm publish完全一致。

验证包内容

# 查看包内文件列表
tar -tf my-lib-1.0.0.tgz

# 解压验证
mkdir tmp && cd tmp
tar -xf ../my-lib-1.0.0.tgz
ls -la package/

模拟真实安装

# 在测试项目中安装本地tgz
cd test-project
npm install ../my-lib-1.0.0.tgz

--dry-run

npm pack --dry-run

仅列出将被打包的文件，不实际生成tgz。

发布前务必执行npm pack --dry-run检查文件列表，避免将源码、测试文件等意外发布到npm。

要点总结

• npm link创建符号链接实现本地实时调试，但与真实安装有差异
• files字段是发布内容的白名单，优先于.npmignore
• npm pack生成与publish一致的tgz包，用于发布前验证
• npm pack --dry-run只预览不生成文件
• 发布流程：npm link调试 → files配置 → npm pack验证 → npm publish